test(search): pin a route-level Supabase round-trip budget for /api/search - #1950

Summary

• Ledger chore(deps-dev): bump prettier from 3.9.0 to 3.9.1 #98 (residual): the offline round-trip budget harness pinned the answer path and the search retrieval core (searchChunksWithTelemetry, in tests/search-round-trip-budget.test.ts), but not the /api/search route itself — its auth, rate limiting, scope resolution, related-document enrichment, and telemetry write were invisible to any budget test. Add tests/search-route-round-trip-budget.test.ts, driving POST from src/app/api/search/route.ts with a counted Supabase client, following the tests/answer-route-preamble.test.ts pattern of importing the route fresh per scenario with vi.doMock. A round trip added anywhere in the route preamble or post-processing is now a red gate instead of something a reviewer has to notice.
• Ledger docs: mark main branch-protection debt as resolved #189: pin the route-level budget from "the harness exists" to an explicit measured count (16 round trips) and exact breakdown for one representative anonymous, filter-free, non-cached search, plus a companion test pinning that a rate-limit denial costs exactly the limiter check (1 round trip) and nothing past it. Separately, disposition the three text-RPC probes: intentional, keep as-is. match_document_chunks_text_v2 and match_document_table_facts_text_v2 are each issued up to 3 times per search — src/lib/rag/rag-candidate-sources.ts fans out maxTextRpcQueryVariants (3) lexical query-variant phrasings (primary + up to two siblings) per text surface, to rescue recall when the primary phrasing misses. This already has a cost-reducing early exit: firstVariantPoolIsStrong (src/lib/rag/rag-retrieval-variants.ts, the "PT-02" mechanism) skips the sibling RPCs once the primary variant's pool is deep and precisely anchored, so a real, well-matched corpus query pays less than ×3 in practice — this test's single-chunk fixture never clears that depth bar, so it measures the worst-case fan-out, not the typical cost. Collapsing the fan-out further (e.g. to a single variant) would be a retrieval-behaviour change and needs the RAG-flag + live-canary process this PR is explicitly out of scope for; no such change is made here.

Three commits, each independently revertible: (1) the route-level harness + non-vacuity checks, (2) pinning the exact count/shape + the ×3 disposition, (3) a small PromiseLike<T> generics fix caught by npm run typecheck (the test harness's mocked query builder needed a two-type-parameter then() to satisfy lib.es5's PromiseLike<T> when a caller passes both onfulfilled and onrejected).

Verification

• npm run test:focused -- --files tests/search-route-round-trip-budget.test.ts — declined, exactly as designed ("Focused test selection is unsafe: test or configuration paths changed"); it fails closed for test-file changes and prints its own follow-up instruction. Ran the full suite instead, per that instruction.
• npm run verify:pr-local -- --files tests/search-route-round-trip-budget.test.ts — full run (this diff is executable/test scope, so it escalates past the docs/workflow fast path). Decisive output:
  • check:runtime — PASS (Node 24.19.0, npm 11.17.0)
  • check:installed-lock-parity — PASS
  • format:changed — "All matched files use Prettier code style!"
  • lint — clean (0 warnings/errors across src tests scripts worker supabase playwright + configs)
  • typecheck — clean (after the fix above)
  • test — Test Files 602 passed (602) / Tests 6511 passed | 4 skipped (6515)
  • check:rag:fixtures — passed
  • check:medication-interactions — "data/medication-interaction-index.json is up to date (523 rows)."
  • One pre-existing, diff-unrelated failure: check:medication-lexicon-report reports docs/medication-interaction-lexicon-review.md as stale. This diff touches exactly one file (tests/search-route-round-trip-budget.test.ts — confirmed via git diff origin/main --name-only); the lexicon doc and its generator were last touched by fix(medications): reach lithium, retire the dead z-drugs term, make lexicon review flags evidence-bearing #1923, well before this branch's point (7a157f4). This is a pre-existing staleness on main, not something this PR introduced.
• npm run verify:ui — not applicable, no UI/routing/styling/browser change.
• npm run verify:release — not run; not a release/handoff-confidence request.
• npm run eval:retrieval:quality — not applicable; no retrieval, ranking, selection, chunking, or scoring behaviour change (this PR only observes existing behaviour through mocked round-trip counting; it changes no production code under src/lib/rag/** or the route itself).
• npm run eval:rag / npm run eval:quality — not applicable; no answer-generation or synthesis-prompt change.
• npm run check:production-readiness — not applicable; no clinical workflow, privacy, environment, Supabase, or source-governance behaviour change (test-only diff).

Risk and rollout

• Risk: none to production behaviour — this PR adds one new test file only; no application, config, or dependency code changed. Worst case if the pinned counts are wrong is a false-positive/false-negative test failure, not a runtime regression.
• Rollback: revert any of the three commits independently — each stands on its own (harness → pinning/disposition → a mechanical type-signature fix to the harness).
• Provider or production effects: None. Fully offline/mocked — RAG_PROVIDER_MODE=offline, a stubbed @/lib/supabase/admin client, and stubbed @/lib/openai. No network, database, or provider calls.

Notes

• This PR touches only tests/search-route-round-trip-budget.test.ts — it does not modify src/app/api/search/route.ts, src/lib/rag/**, or any other production/ranking surface, so no Clinical Governance Preflight or RAG impact: line applies (confirmed against scripts/pr-policy.mjs's classifyPullRequestFiles: the changed path matches neither clinicalRiskPatterns nor ragRankingPatterns).

Generated by Claude Code